/* Copyright (c) 2025 Beijing Semidrive Technology Corporation
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/** *****************************************************************************************************
 *  \file     Mcu_Rtc.h                                                                                 *
 *  \brief    This file contains interface header for MCU_Rtc MCAL driver                               *
 *                                                                                                      *
 * <table>                                                                                              *
 * <tr><th>Date           <th>Version                                                                   *
 * <tr><td>2023/08/03     <td>1.0.0                                                                     *
 * </table>                                                                                             *
 *******************************************************************************************************/

#ifndef MCU_RTC_H
#define MCU_RTC_H


#ifdef __cplusplus
extern "C" {
#endif
/********************************************************************************************************
 *                                      Include header files                                            *
 *******************************************************************************************************/
#include "Std_Types.h"
#include "Mcal.h"
#include "Mcu_Cfg.h"

/********************************************************************************************************
 *                                 Global Macro definition                                              *
 *******************************************************************************************************/
/**
 * \brief  The RTC Timer Redundancy Mode
 *
 * Enabling RTC Timer Redundancy Mode configures RTC2 as a Slave,
 * making it unavailable for independent use.
 *
 */
#define RTC_TIMER_REDUNDANCY_MODE
/** \brief  The Rtc Redundant Timer base address */
#ifdef RTC_TIMER_REDUNDANCY_MODE
#define RTC_TIMER_REDUDANCY_BASE  APB_RTC2_BASE
#endif

/** \brief  The RTC Timer tick max value. */
#define RTC_TICK_MAX    0xffffffffffffull

/**
 *  \name RTC Error Codes
 *
 *  Error codes returned by RTC functions
 *
 */
/** \brief  ERROR:Error due to timeout occurred. */
#define RTC_E_TIMEOUT    ((uint8)0x81U)

/** \brief  ERROR:Error due invalid parameters. */
#define RTC_E_PARAMS     ((uint8)0x82U)

/** \brief  ERROR:Error due the RTC ctrl register is locked. */
#define RTC_E_LOCKED     ((uint8)0x83U)

/** \brief  ERROR:Error due to invalid hardware status. */
#define RTC_E_HW_STATUS  ((uint8)0x84U)

/** \brief  ERROR:Error due Redundancy check fail. */
#define RTC_E_RDN        ((uint8)0x85U)

/********************************************************************************************************
 *                                  Global Types definition                                             *
 *******************************************************************************************************/
/** \brief  RTC Timer Hardware module support. */
typedef enum
{
    RTC1 = 0U,
#ifndef RTC_TIMER_REDUNDANCY_MODE
    RTC2,
#endif
    ALL,
} Mcu_RtcChannelType;

/** \brief  RTC Timer Hardware mode support. */
typedef enum
{
    RTC_TIMER_MODE_SEC = 0U,
    RTC_TIMER_MODE_MIN,
    RTC_TIMER_MODE_INVALID = 0xFFU,
} Mcu_RtcTimerModeType;

/** \brief  RTC Time Member description. */
typedef struct
{
    uint8  seconds;             /** \brief seconds of the minute, [0,59] */
    uint8  minutes;             /** \brief minutes of the hour, [0,59] */
    uint8  hours;               /** \brief hour of the day, [0,23] */
    uint8  weekday;             /** \brief Weekday since Sun, [0,6] */
    uint8  day;                 /** \brief day of the month, [1,31] */
    uint8  month;               /** \brief months since Jan, [0,11] */
    uint16 year;                /** \brief years since 1970 */
} Mcu_RtcTimeType;

/** \brief  RTC Alarm Time Member description. */
typedef struct
{
    uint8  seconds;             /** \brief seconds of the minute, [0,59] */
    uint8  minutes;             /** \brief minutes of the hour, [0,59] */
    uint8  hours;               /** \brief hour of the day, [0,23] */
    uint8  weekday;             /** \brief Weekday since Sun, [0,6] */
    uint8  day;                 /** \brief day of the month, [1,31] */
} Mcu_RtcAlarmTimeType;

/** \brief  RTC Sleep Time attribute description. */
typedef uint16 Mcu_RtcSleepTimeType;

/** \brief  RTC Timer Callback notification type. */
typedef uint32 (*Mcu_AlarmNotifyType)(void *para);

/** \brief  RTC Timer Adjust type. */
typedef struct
{
    uint16 period;              /** \brief period to do Increase (or Decrease) */
    uint16 cycle;               /** \brief the cycles will be added to (or substracted from) rtc
                                        counter per period * 1024 rtc cycles */
    boolean direction;          /** \brief 0 - Increase; 1 - Decrease */
    /*PRQA S 1535 1*/
} Mcu_RtcAdjustType;

/** \brief  RTC Timer Alarm type. */
typedef struct
{
    Mcu_RtcChannelType channel;
    Mcu_RtcTimerModeType timerMode1;    /** \brief 0 - sec; 1 - min */
    uint16       timer1;                /** \brief rtc timer counter */
    Mcu_RtcTimerModeType timerMode2;    /** \brief 0 - sec; 1 - min */
    uint16       timer2;                /** \brief rtc timer counter */
} Mcu_RtcAlarmType;

/********************************************************************************************************
 *                                  Global Function Declarations                                        *
 *******************************************************************************************************/

/** *****************************************************************************************************
 * \brief This function is used to enable RTC Timer.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_RtcEnable
 *                      (
 *                          uint32 base
 *                      )
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - The RTC Timer base address.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK - The Executed successfully.
 *                      MCU_E_REGLOCKED - The RTC Timer is locked.
 *                      MCU_E_TIMEOUT - The wait tmeout.
 *
 * Description        : Frequently disabling the RTC Timer may trigger the rtc_disable interrupt.
 *                      User must manually clear the rtc_disable interrupt flag.
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_RtcEnable(uint32 base);

/** *****************************************************************************************************
 * \brief This function is used to disable RTC Timer.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_RtcDisable
 *                      (
 *                          uint32 base
 *                      )
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - The RTC Timer base address.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK - The Executed successfully.
 *                      MCU_E_REGLOCKED - The RTC Timer is locked.
 *                      MCU_E_TIMEOUT - The wait tmeout.
 *
 * Description        : Frequently disabling the RTC Timer may trigger the rtc_disable interrupt.
 *                      User must manually clear the rtc_disable interrupt flag.
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_RtcDisable(uint32 base);

/** *****************************************************************************************************
 * \brief This function is used to interrupt handle for RTC Timer1.
 *
 * \verbatim
 * Syntax             : void Mcu_Ip_RtcIrqHandler1
 *                      (
 *                          void
 *                      )
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : None
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        :
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
ISR(Mcu_Ip_RtcIrqHandler1);

/** *****************************************************************************************************
 * \brief This function is used to interrupt handle for RTC Timer2.
 *
 * \verbatim
 * Syntax             : void Mcu_Ip_RtcIrqHandler2
 *                      (
 *                          void
 *                      )
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : None
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : None
 *
 * Description        :
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
ISR(Mcu_Ip_RtcIrqHandler2);

/** *****************************************************************************************************
 * \brief This function is used to set time for RTC Timer.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_RtcSetTime
 *                      (
 *                          uint32 base,
 *                          Mcu_RtcTimeType *rtcTimePtr
 *                      )
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - The RTC Timer base address.
 *                      rtcTimePtr - The time pointer.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK - The Executed successfully.
 *                      MCU_E_PARAM_POINTER - The Parameter NULL.
 *
 * Description        :
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_RtcSetTime(uint32 base, const Mcu_RtcTimeType *const rtcTimePtr);

/** *****************************************************************************************************
 * \brief This function is used to get time for RTC Timer.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_RtcGetTime
 *                      (
 *                          uint32 base,
 *                          Mcu_RtcTimeType *rtcTimePtr
 *                      )
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - The RTC Timer base address.
 *                      rtcTimePtr - The time pointer.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK - The Executed successfully.
 *                      MCU_E_PARAM_CONFIG - The Parameter invalid.
 *                      MCU_E_TIMEOUT - The Wait timeout.
 *
 * Description        :
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_RtcGetTime(uint32 base, Mcu_RtcTimeType *rtcTimePtr);

/** *****************************************************************************************************
 * \brief This function is used to set alarm time for RTC Timer.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_RtcSetAlarmTime
 *                      (
 *                          uint32 base,
 *                          Mcu_RtcAlarmTimeType *rtcAlarmTimePtr,
 *                          Mcu_AlarmNotifyType notify
 *                      )
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - The RTC Timer base address.
 *                      rtcAlarmTimePtr - The alarm time pointer.
 *                      notify - The RTC Timer alarm Notification function.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK - The Executed successfully.
 *                      MCU_E_PARAM_CONFIG - The Parameter invalid.
 *                      MCU_E_TIMEOUT - The Wait timeout.
 *
 * Description        : When the alarm is set, the current tick value is automatically read. If the
 *                      set alarm value is smaller than this tick, the setting does not take effect.
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_RtcSetAlarmTime(uint32 base,
                                      const Mcu_RtcAlarmTimeType *const rtcAlarmTimePtr,
                                      Mcu_AlarmNotifyType notify);

/** *****************************************************************************************************
 * \brief This function is used to get alarm time for RTC Timer.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_RtcGetAlarmTime
 *                      (
 *                          uint32 base,
 *                          Mcu_RtcAlarmTimeType *rtcAlarmTimePtr
 *                      )
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - The RTC Timer base address.
 *                      rtcAlarmTimePtr - The alarm time pointer.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK - The Executed successfully.
 *                      MCU_E_PARAM_CONFIG - The Parameter invalid.
 *                      MCU_E_TIMEOUT - The Wait timeout.
 *
 * Description        : Before calling this function, you must call Mcu_Ip_RtcSetAlarmTime to set
 *                      the alarm value and enable IRQ_enable.
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_RtcGetAlarmTime(uint32 base, Mcu_RtcAlarmTimeType *rtcAlarmTimePtr);

/** *****************************************************************************************************
 * \brief This function is used to clear counter for RTC Timer.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_RtcClearTimerCounter
 *                      (
 *                          uint32 base
 *                      )
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - The RTC Timer base address.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK - The Executed successfully.
 *                      MCU_E_REGLOCKED - is locked.
 *                      E_NOT_OK - The Parameter invalid.
 *                      MCU_E_TIMEOUT - The Wait timeout.
 *
 * Description        : After clearing the RTC Timer counter, the user must re-enable the RTC Timer.
 *
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_RtcClearTimerCounter(uint32 base);

/** *****************************************************************************************************
 * \brief This function is used to clear IRQ status for RTC Timer.
 *
 * \verbatim
 * Syntax             : Std_ReturnType Mcu_Ip_RtcClearIrqFlag
 *                      (
 *                          uint32 base
 *                      )
 *
 * Service ID[hex]    : None
 *
 * Sync/Async         : Synchronous
 *
 * Reentrancy         : Non reentrant
 *
 * Parameters (in)    : base - The RTC Timer base address.
 *
 * Parameters (inout) : None
 *
 * Parameters (out)   : None
 *
 * Return value       : E_OK - The Executed successfully.
 *                      MCU_E_TIMEOUT - The wait timeout.
 *
 * Description        : When interrupt nesting is enabled in the interrupt handler function, if the
 *                      Mcu_Ip_RtcClearIrqFlag function is called with IRQ turned on again, it
 *                      is possible to get caught in a loop during the process of clearing the
 *                      interrupt state of the RTC Timer (it is strongly recommended to disable IRQ
 *                      enable first). When the RTC Timer is in the 32KHzdomian state, the CPU can
 *                      perform the next operation only after signal synchronization is complete.
 * \endverbatim
 * Traceability       :
 *******************************************************************************************************/
Std_ReturnType Mcu_Ip_RtcClearIrqFlag(uint32 base);

#ifdef __cplusplus
}
#endif

#endif /* MCU_RTC_H */
/* End of file */
